home *** CD-ROM | disk | FTP | other *** search
/ SGI Performance Co-Pilot 1.3 / SGI Performance Co-Pilot 1.3.iso / dist / dist6.4 / pcp.idb / usr / share / catman / u_man / cat3 / PMAPI / pmdafetch.z.z / pmdafetch.z / pmdafetch
Text File  |  1997-04-03  |  11KB  |  199 lines
  1.  
  2.  
  3.  
  4. PPPPMMMMDDDDAAAAFFFFEEEETTTTCCCCHHHH((((3333))))                                                      PPPPMMMMDDDDAAAAFFFFEEEETTTTCCCCHHHH((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ppppmmmmddddaaaaFFFFeeeettttcccchhhh, ppppmmmmddddaaaaSSSSeeeettttFFFFeeeettttcccchhhhCCCCaaaallllllllBBBBaaaacccckkkk - fill a pmResult structure with the
  10.      requested metric values
  11.  
  12. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppccccpppp////ppppmmmmaaaappppiiii....hhhh>>>>
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppccccpppp////iiiimmmmppppllll....hhhh>>>>
  15.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppccccpppp////ppppmmmmddddaaaa....hhhh>>>>
  16.  
  17.      iiiinnnntttt ppppmmmmddddaaaaFFFFeeeettttcccchhhh((((iiiinnnntttt nnnnuuuummmmppppmmmmiiiidddd,,,, ppppmmmmIIIIDDDD ppppmmmmiiiiddddlllliiiisssstttt[[[[]]]],,,, ppppmmmmRRRReeeessssuuuulllltttt ********rrrreeeesssspppp,,,, ppppmmmmddddaaaaEEEExxxxtttt
  18.      ****ppppmmmmddddaaaa))));;;;
  19.  
  20.      vvvvooooiiiidddd ppppmmmmddddaaaaSSSSeeeettttFFFFeeeettttcccchhhhCCCCaaaallllllllBBBBaaaacccckkkk((((ppppmmmmddddaaaaIIIInnnntttteeeerrrrffffaaaacccceeee ****ddddiiiissssppppaaaattttcccchhhh,,,, ppppmmmmddddaaaaFFFFeeeettttcccchhhhCCCCaaaallllllllBBBBaaaacccckkkk
  21.      ccccaaaallllllllbbbbaaaacccckkkk))));;;;
  22.  
  23.      cccccccc ............ ----llllppppccccpppp____ppppmmmmddddaaaa ----llllppppccccpppp
  24.  
  25. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  26.      ppppmmmmddddaaaaFFFFeeeettttcccchhhh is a generic callback used by a PPPPMMMMDDDDAAAA(3) to process a fetch
  27.      request from ppppmmmmccccdddd(1).  The request from ppppmmmmccccdddd is initiated by a client
  28.      calling ppppmmmmFFFFeeeettttcccchhhh(3).
  29.  
  30.      This is the only generic callback (see PPPPMMMMDDDDAAAA(3)) that is incomplete,
  31.      requiring a callback of it's own.  The additional callback should be
  32.      registered using ppppmmmmddddaaaaSSSSeeeettttFFFFeeeettttcccchhhhCCCCaaaallllllllBBBBaaaacccckkkk....
  33.  
  34.      ppppmmmmddddaaaaFFFFeeeettttcccchhhh will allocate and resize the _r_e_s_p result structure, to store
  35.      values for the _n_u_m_p_m_i_d metrics listed in _p_m_i_d_l_i_s_t.
  36.  
  37.      For each instance listed in the profile (see ppppmmmmddddaaaaPPPPrrrrooooffffiiiilllleeee(3)) of each
  38.      metric listed in _p_m_i_d_l_i_s_t, the registered callback is required to fill a
  39.      ppppmmmmAAAAttttoooommmmVVVVaaaalllluuuueeee structure with the metric's value.  This value is then copied
  40.      into the ppppmmmmRRRReeeessssuuuulllltttt structure.
  41.  
  42.      For example, a PMDA has two metrics (A and B) and an instance domain (X)
  43.      with two instances (X1 and X2).  The instance domain and metrics
  44.      description tables (see ppppmmmmddddaaaaIIIInnnniiiitttt(3)) could be defined as:
  45.  
  46.           static pmdaInstid _X[] = {
  47.               { 0, "X1" }, { 1, "X2" }
  48.           };
  49.  
  50.           static pmdaIndom indomtab[] = {
  51.           #define X_INDOM     0
  52.               { 0, 2, _X },
  53.           };
  54.  
  55.           static pmdaMetric metrictab[] = {
  56.           /* A */
  57.               { (void *)0,
  58.                 { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
  59.                   { 0,0,0,0,0,0} }, },
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPMMMMDDDDAAAAFFFFEEEETTTTCCCCHHHH((((3333))))                                                      PPPPMMMMDDDDAAAAFFFFEEEETTTTCCCCHHHH((((3333))))
  71.  
  72.  
  73.  
  74.           /* B */
  75.               { (void *)0,
  76.                 { PMDA_PMID(0,1), PM_TYPE_DOUBLE, X_INDOM, PM_SEM_INSTANT,
  77.                   { 0,1,0,0,PM_TIME_SEC,0} }, },
  78.           };
  79.  
  80.      A callback for ppppmmmmddddaaaaFFFFeeeettttcccchhhh could be defined as:
  81.  
  82.           static int
  83.           myFetchCallBack(pmdaMetric *mdesc, unsigned int inst, pmdaAtomValue *atom)
  84.           {
  85.               _pmID_int    *idp = (_pmID_int *)&(mdesc->m_desc.pmid);
  86.  
  87.               switch (idp->item) {
  88.                   case 0:
  89.                       atom->l = /* assign some value for metric A */;
  90.                    break;
  91.                   case 1:
  92.                       switch (inst) {
  93.                           case 0:
  94.                               atom->d = /* assign a value for metric A, instance X1 */;
  95.                               break;
  96.                           case 1:
  97.                               atom->d = /* assign a value for metric A, instance X2 */;
  98.                               break;
  99.                     default:
  100.                         return PM_ERR_INST;
  101.                       }
  102.                default:
  103.                    return PM_ERR_PMID;
  104.               }
  105.               return 0;
  106.           }
  107.  
  108.      The metric description _m_d_e_s_c and the instance identifier _i_n_s_t are used to
  109.      determine which metric and instance is required.  The callback should
  110.      return 0000 unless the PMID or the instance are not supported, in which case
  111.      PPPPMMMM____EEEERRRRRRRR____PPPPMMMMIIIIDDDD or PPPPMMMM____EEEERRRRRRRR____IIIINNNNSSSSTTTT should be returned, respectively.  If an
  112.      instance is not currently available, the callback should return
  113.      PPPPMMMM____EEEERRRRRRRR____AAAAGGGGAAAAIIIINNNN.
  114.  
  115. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  116.      The following error messages indicate that there is discrepancy between
  117.      the namespace, ppppmmmmddddaaaaMMMMeeeettttrrrriiiicccc and ppppmmmmddddaaaaIIIInnnnddddoooommmm tables passed to ppppmmmmddddaaaaIIIInnnniiiitttt(3), and
  118.      the registered fetch callback:
  119.  
  120.      ppppmmmmddddaaaaFFFFeeeettttcccchhhh:::: RRRReeeeqqqquuuueeeesssstttteeeedddd mmmmeeeettttrrrriiiicccc _m_e_t_r_i_c iiiissss nnnnooootttt ddddeeeeffffiiiinnnneeeedddd
  121.                     A requested metric _m_e_t_r_i_c is not listed in the ppppmmmmddddaaaaMMMMeeeettttrrrriiiicccc
  122.                     table.  The namespace for this PPPPMMMMDDDDAAAA(3) may contain
  123.                     additional metrics.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPMMMMDDDDAAAAFFFFEEEETTTTCCCCHHHH((((3333))))                                                      PPPPMMMMDDDDAAAAFFFFEEEETTTTCCCCHHHH((((3333))))
  137.  
  138.  
  139.  
  140.      ppppmmmmddddaaaaFFFFeeeettttcccchhhh:::: PPPPMMMMIIIIDDDD _p_m_i_d nnnnooootttt hhhhaaaannnnddddlllleeeedddd bbbbyyyy ffffeeeettttcccchhhh ccccaaaallllllllbbbbaaaacccckkkk
  141.                     The fetch callback has returned PPPPMMMM____EEEERRRRRRRR____PPPPMMMMIIIIDDDD.  This
  142.                     indicates that a metric may be listed in the ppppmmmmddddaaaaMMMMeeeettttrrrriiiicccc
  143.                     table, but is not supported by the callback.
  144.  
  145.      ppppmmmmddddaaaaFFFFeeeettttcccchhhh:::: IIIInnnnssssttttaaaannnncccceeee _i_n_s_t ooooffff PPPPMMMMIIIIDDDD _p_m_i_d nnnnooootttt hhhhaaaannnnddddlllleeeedddd bbbbyyyy ffffeeeettttcccchhhh ccccaaaallllllllbbbbaaaacccckkkk
  146.                     The fetch callback has returned PPPPMMMM____EEEERRRRRRRR____IIIINNNNSSSSTTTT.  This
  147.                     indicates that an instance of metric is listed in the
  148.                     ppppmmmmddddaaaaIIIInnnnddddoooommmm table, but is not supported by the callback.
  149.  
  150.      ppppmmmmddddaaaaFFFFeeeettttcccchhhh:::: FFFFeeeettttcccchhhh ccccaaaallllllllbbbbaaaacccckkkk eeeerrrrrrrroooorrrr::::
  151.                     The fetch callback returned a result other than 0000,
  152.                     PPPPMMMM____EEEERRRRRRRR____PPPPMMMMIIIIDDDD or PPPPMMMM____EEEERRRRRRRR____IIIINNNNSSSSTTTT.
  153.  
  154.      ppppmmmmddddaaaaFFFFeeeettttcccchhhh:::: DDDDeeeessssccccrrrriiiippppttttoooorrrr ttttyyyyppppeeee ((((_t_y_p_e)))) ffffoooorrrr mmmmeeeettttrrrriiiicccc _p_m_i_d iiiissss bbbbaaaadddd
  155.                     The data type _t_y_p_e specified for the metric _p_m_i_d in the
  156.                     ppppmmmmddddaaaaMMMMeeeettttrrrriiiicccc table is illegal.
  157.  
  158.      ppppmmmmddddaaaaFFFFeeeettttcccchhhh will return ----eeeerrrrrrrrnnnnoooo if an error occurred while allocating the
  159.      ppppmmmmRRRReeeessssuuuulllltttt structure or copying the value from the ppppmmmmAAAAttttoooommmmVVVVaaaalllluuuueeee.
  160.  
  161. CCCCAAAAVVVVEEEEAAAATTTT
  162.      The PMDA must be using PPPPMMMMDDDDAAAA____PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL____2222 or later, as specified in the call
  163.      to ppppmmmmddddaaaaDDDDSSSSOOOO(3) or ppppmmmmddddaaaaDDDDaaaaeeeemmmmoooonnnn(3).
  164.  
  165. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  166.      ppppmmmmccccdddd(1), PPPPMMMMDDDDAAAA(3), ppppmmmmddddaaaaDDDDSSSSOOOO(3), ppppmmmmddddaaaaDDDDaaaaeeeemmmmoooonnnn(3), ppppmmmmFFFFeeeettttcccchhhh(3) and ppppmmmmddddaaaaIIIInnnniiiitttt(3).
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.